Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support
Apple IIGS
#53:    Desk Accessories and Tools

Written by:    Matt Deatherage & Jim Mensch                        March 1989

This Technical Note describes new guidelines for developers to help 
applications and desk accessories live together in the same system at the same 
time.
_____________________________________________________________________________


Introduction

Desk accessories vary widely in complexity.  Classic Desk Accessories (CDAs) 
range from simple status-reporting programs to complete system-level debugging 
utilities, and similarly, New Desk Accessories (NDAs) range from static 
windows with pictures to nearly full-fledged applications.

This Note presents some new guidelines aimed at helping developers of both 
applications and desk accessories to get their products to work together now 
and in the future.


Tool Sets

The greatest current conflict between applications and desk accessories, 
especially NDAs, is the use of system tool sets.  The Apple IIGS Toolbox 
Reference, Volume 1, defines which tools are available for use by NDAs.  The 
Desk Manager requires starting the following tool sets before calling 
FixAppleMenu (which installs the names of the NDAs in the Apple menu):

    Tool Locator (#1)
    Memory Manager (#2)
    Miscellaneous Tools (#3)
    QuickDraw II (#4)
    Event Manager (#5)
    Window Manager (#14)
    Menu Manager (#15)
    Control Manager (#16)
    LineEdit (#20)
    Dialog Manager (#21)
    Scrap Manager (#22)

Since the Desk Manager requires starting these tools before calling 
FixAppleMenu, NDAs may assume that these tools are all present and running, so 
they do not need to check for their presence.  

In addition to these requirements by the Desk Manager, Apple II Developer 
Technical Support strongly recommends that all applications start the 
following tools:

    QuickDraw Auxiliary (#16)
    Font Manager (#27)

These two additional tools are so widely used by desk accessories that they 
should be present.  An NDA may not assume their presence, but any application 
that calls FixAppleMenu should also start these two tools.


The Golden NDA Guideline

Developers who wish to maintain maximum compatibility between their NDAs and 
applications, both now and in the future, should consider every environment 
change they make with the following Golden NDA Guideline firmly in mind:

    "I, an NDA, pledge not to alter the environment of the application 
    under which I run, and I will behave in such a way that the 
    application runs the same whether I am present or not."

Of course, this guideline does not include such necessary tasks as the normal 
(and reasonable) allocation of memory.  An application must be prepared to 
handle a memory allocation call by a desk accessory, operating system, or even 
a tool at unexpected times.  The guideline does, however, mean that your desk 
accessory cannot change the operating environment, including such things as 
the presence of tools and operating system parameters.  The following sections 
detail some of the most important ways of following the Golden NDA Guideline.


Desk Accessory Guidelines

Extra Tools

o    If an NDA wishes to use a tool which is not available in the standard 
     list (e.g., Standard File), it should check to see if the tool is 
     already running.  If it is not running, the NDA must use LoadOneTool to 
     load it, then it must start the tool before using it.  When finished 
     with the tool, the NDA must shut it down and unload it with 
     UnloadOneTool.

o    If an NDA wishes to use a tool which is not available in the standard 
     list and the NDA wants to use it in a non-modal fashion, then it has 
     even more work to do.  In addition to the conditions set for a tool 
     which is not available in the standard list, if your NDA uses a tool in 
     a non-modal fashion, you must shut it down and unload it when your 
     window is deactivated.

     The Golden NDA Guideline shows why this is true.  If your NDA started a 
     tool which the application was going to use but had not yet started 
     (i.e., the Font Manager), and your NDA does not shut it down when the 
     application takes control of the system, the application will get error 
     $1B01 (Font Manager Already Started) when it makes the FMStartUp call, 
     and this error can cause the application to fail.

     Therefore, when your window is deactivated, if you shut down all the 
     tools you have started, the application will be free to start those 
     tools which it requires.  When your window is reactivated, you must 
     check the status of each tool in question then reload and restart those 
     which are not present before reusing them.

     In this case, the Golden NDA Guideline means that an application must 
     not be forced to check the status of a tool which it has not started.  
     Applications are not required to do so, and most of them do not.

o    Sound tools provide the one exception to the rule of freely using a 
     tool which is already started.  Refer to the section on System 
     Parameters for more details on using sound tools.

o    An NDA must not shut down tools which it has not started.  If you 
     start a tool then shut it down when finished with it, you must be sure 
     not to accidently shut it down the next time your window is deactivated.

o    A CDA is nearly always modal, but it has the capability to install 
     HeartBeat Tasks and other ways of being called after returning to an 
     application (which could be running under ProDOS 8).  If a CDA installs 
     a method of performing tasks after the user has returned to the 
     application, it must be careful not to use any tools which are not 
     started, since the list of available tools for NDAs does not hold true 
     for CDAs.

System Parameters

o    A desk accessory (CDA or NDA) must not change a system resource or 
     parameter which cannot be restored to its original condition.  A 
     trivial, but illustrative, example of this is the number of times a 
     pull-down menu item blinks when you select it.  This number (three by 
     default) may be changed with the SetMItemBlink call, but there is not 
     corresponding GetMItemBlink call, so you cannot retrieve the current 
     value.  Therefore, a desk accessory must not change this parameter, and 
     the same rule applies to any other system parameter for which you cannot 
     determine a current value.

o    This idea extends to calling tool startup functions.  Even if a tool's 
     startup function does not return an error if the tool is already active, 
     it may reset certain parameters upon which the application depends.  An 
     example of this is TLStartUp for the Tool Locator.  A seemingly 
     innocuous call, TLStartUp actually disconnects any user tool sets 
     present, which, in this case, would most likely have been installed by 
     the current application.

     A desk accessory should not call any tool's startup function if the 
     tool is already active.  The one exception to this rule is the Memory 
     Manager's MMStartUp call, which a desk accessory may make to obtain its 
     User ID.  MMStartUp may be considered equivalent to a GetMyID call.

o    A desk accessory cannot use any of the sound tools if they are 
     already started.  This is contrary to all other tool sets, but it is 
     required in this case since there is no memory management of the sound 
     RAM.  If the Sound Tools (#8) are started, the application has exclusive 
     control of the 64K DOC RAM used to play sounds.  Anything your desk 
     accessory might put there is likely to overwrite information the 
     application needs.

     Saving and restoring DOC RAM around desk accessory usage is not 
     sufficient.  Many of the sound functions are interrupt-driven, altering 
     the contents of DOC RAM only at sound interrupts, so your desk accessory 
     might attempt to replace parts of DOC RAM which are being played.  Since 
     there is no memory management of DOC RAM, desk accessories must avoid 
     the sound functions of the IIGS if the application is already using 
     them.

o    A desk accessory must not install user tool sets, because there is no 
     arbitration of user tool set numbers.


Application Guidelines

To coexist peacefully with desk accessories, particularly NDAs, applications 
generally need to follow the guidelines listed in the Desk Manager chapter of 
the Apple IIGS Toolbox Reference, Volume 1.  However, those applications which 
wish to ensure maximum compatibility now and in the future will also want to 
adhere to the following:

o    Don't just start the Scrap Manager--use it.  Many desk accessories are 
     capable of cutting and pasting information between themselves and your 
     application, but they cannot do so if you do not use the Scrap Manager.  
     If you handle the Edit menu functions privately, without placing the 
     information on your internal clipboard in the public scrap, a desk 
     accessory will not be able to access it.  This inability to share 
     information frustrates both the users and the developers who write desk 
     accessories.

o    Start tools at the beginning of your application and leave them 
     started.  Every time you call SystemTask or TaskMaster, a desk accessory 
     might take control of the system, and if your application has shut down 
     a tool that a desk accessory found running and is using, it might not be 
     able to complete an operation.  For example, a desk accessory might be 
     using the Print Manager, having found it started by your application.  
     If your application takes control of the system and shuts down the Print 
     Manager while the desk accessory is printing a document, the desk 
     accessory will not be able to finish when it regains control.

     For maximum compatibility, do not shut down any tools which were ever 
     active when you called SystemTask or TaskMaster.  You can start more 
     tools, but do not shut down those which are already active.  If you 
     intend to start a tool and not keep it started, use it then shut it down 
     immediately, being sure not to call SystemTask or TaskMaster during that 
     time.

o    An application with some memory to spare can save NDAs time by 
     providing them the additional tools which they are most likely to use.  
     If a desk accessory wishes to use the List Manager and your application 
     starts it, the desk accessory will naturally run faster since it will 
     succeed on the ListStatus call every time and can avoid loading and 
     starting the tool on every activation.

     The most common tools which desk accessories require besides those 
     available in the standard Desk Manager set are QuickDraw Auxiliary 
     (#16), the Print Manager (#19), Standard File (#24), the Font Manager 
     (#27), and the List Manager (#28).  QuickDraw Auxiliary and the Font 
     Manager are especially important--not only do they work well together, 
     but they are also widely used.  In addition, FMStartUp can take a long 
     time, and waiting for it every time you activate an NDA window gets 
     really frustrating.  Many desk accessories also use the Print Manager, 
     the List Manager, and Standard File, and if they are always available, 
     desk accessories will work more smoothly with your application.


Further Reference:
_____________________________________________________________________________
    o    Apple IIGS Toolbox Reference, Volume 1
    o    Programmer's Introduction to the Apple IIGS